home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 12 / BBS in a box XII-1.iso / Files / System7 tools / M / Menu Events 1.1.1.sit / Menu Events 1.1.1 / Menu Events Help.rsrc / STR#_1027.txt < prev    next >
Encoding:
Text File  |  1994-04-12  |  5.1 KB  |  211 lines
  1. 
  2.  
  3. 
  4.  
  5. ‹
  6.  
  7. ‹
  8.  
  9. √•How Does Menu Events Work?
  10.  
  11. 
  12.  
  13. 
  14.  
  15. When you send a Query Menu List or Query Menu event, the ideal
  16.  
  17. application will dispatch the resulting high-level event as an Apple event
  18.  
  19. without looking at it.  The event handler provided by Menu Events forms a
  20.  
  21. reply to the query on the basis of the application‚Äôs menu list structure.  If
  22.  
  23. the case of a Query Menu event, if the given menu ID is not valid, it
  24.  
  25. returns noSuchMenuErr; if the given menu uses a non-standard menu
  26.  
  27. definition function ('MDEF'), it returns nonStandardMenuErr.  Through all
  28.  
  29. of this, the application stays in the background or in the foreground,
  30.  
  31. wherever it was before.
  32.  
  33. 
  34.  
  35. 
  36.  
  37. When you send a Select Menu Item event, the same things happen, but the
  38.  
  39. event handling is more complex.
  40.  
  41. 
  42.  
  43. First, it verifies that the given menu item is valid and enabled.  If not, it
  44.  
  45. returns noSuchMenuErr, nonStandardMenuErr, noSuchMenuItemErr, or
  46.  
  47. menuItemDisabledErr.
  48.  
  49. 
  50.  
  51. Second, it asks for the application to be brought to the front for user
  52.  
  53. interaction, because it could be dangerous to feed the target application a
  54.  
  55. menu selection while it is in the background, something which never
  56.  
  57. happens in normal operation.  If it is refused, it returns
  58.  
  59. errAENoUserInteraction.
  60.  
  61. 
  62.  
  63. Third, it patches some traps so that it can gain control of menu selection.
  64.  
  65. If it finds that the patches are already in place, meaning that an earlier
  66.  
  67. Menu event is still pending, it returns menuEventPendingErr.
  68.  
  69. 
  70.  
  71. Fourth, if everything is OK, it posts an event to simulate a mouse click in
  72.  
  73. the menu bar.  The application habitually asks which menu item was
  74.  
  75. selected, and the patched traps provide the given item in response.  The
  76.  
  77. patches then remove themselves.  From there, it is exactly as though the
  78.  
  79. user had actually made the selection.
  80.  
  81. 
  82.  
  83. NOTE:  When replying to any of the three event types, Menu Events
  84.  
  85. includes a null ‚Äútattoo‚Äù parameter to prove that it handled the event,
  86.  
  87. rather than some handler supplied by the application.  Many Microsoft
  88.  
  89. applications, for example, bind their own handler over all Apple event
  90.  
  91. classes, preventing Menu Events from working.  (The handler wouldn‚Äôt be
  92.  
  93. a problem if it returned errAEEventNotHandled when faced with an
  94.  
  95. unknown Apple event, as it should.)
  96.  
  97. 
  98.  
  99. 
  100.  
  101. 
  102.  
  103. xUser Interaction Policy
  104.  
  105. 
  106.  
  107. The Apple Event Manager implements a complicated but sensible model for
  108.  
  109. joint sender/receiver control over user interaction.  Menu Events doesn‚Äôt
  110.  
  111. know which menu selections will really require user interaction, but even
  112.  
  113. if it did, it would still have to request user interaction just to bring the
  114.  
  115. target application to the front, where an application always expects to be
  116.  
  117. when it sees a mouse-down event.
  118.  
  119. 
  120.  
  121. 
  122.  
  123. The sending program must set the kAECanInteract or kAEAlwaysInteract
  124.  
  125. flag in the sendMode parameter to AESend, in order to achieve user
  126.  
  127. interaction.  It should also set the kAECanSwitchLayer flag, allowing the
  128.  
  129. target application to come to the front without having to post a
  130.  
  131. notification request.  If the target application is in the background, and
  132.  
  133. receives a Menu event with this flag not set, it will go into a notification
  134.  
  135. wait state, which may disrupt its usual background event processing
  136.  
  137. behavior.
  138.  
  139. 
  140.  
  141. If both the sending program and target application are in the background,
  142.  
  143. the kAECanSwitchLayer flag has no effect, and the notification request is
  144.  
  145. posted anyway.  Since your sending program is indirectly instigating a
  146.  
  147. user interaction, it should call AEInteractWithUser before sending the
  148.  
  149. Menu event, if there is any chance that it will be in the background at the
  150.  
  151. time.  Another approach would be to call SetFrontProcess to activate the
  152.  
  153. target application before sending it a Menu event.
  154.  
  155. 
  156.  
  157. If the target application is in that rare user interaction state,
  158.  
  159. kAEInteractWithSelf, where it disallows interaction requested by any
  160.  
  161. other process, the Menu event handler will respect that state, and refuse
  162.  
  163. the event.
  164.  
  165. 
  166.  
  167. If the sending and receiving applications are on different machines, the
  168.  
  169. usual program linking checks apply, namely, Sharing Setup (on/off),
  170.  
  171. Users & Groups (permission to user), and Finder‚Äôs Sharing (permission to
  172.  
  173. application).
  174.  
  175. 
  176.  
  177. If the Menu Events extension is locked, using Finder‚Äôs Get Info dialog, then
  178.  
  179. only target applications which explicitly allow interaction with all
  180.  
  181. processes can be controlled by remote senders.  If it is not locked, and if
  182.  
  183. it sees that the user interaction state is kAEInteractWithLocal, which is
  184.  
  185. the default value, it will momentarily change it to kAEInteractWithAll, so
  186.  
  187. that events sent from a remote machine are not rejected.  This trick is
  188.  
  189. necessary for Menu Events to be useful with most target applications,
  190.  
  191. because most will assume the default interaction state, not expecting any
  192.  
  193. remote sender to require user interaction.  The icon displayed by Menu
  194.  
  195. Events at startup shows whether or not the lock is in effect.
  196.  
  197. 
  198.  
  199. IMPORTANT NOTE:  Users of machines where Menu Events is installed
  200.  
  201. should be careful about which users and applications are enabled for
  202.  
  203. remote program linking.  In particular, guest users should not be allowed
  204.  
  205. to do program linking unless Menu Events is locked.
  206.  
  207. 
  208.  
  209. 
  210.  
  211.